Inside Macintosh: QuickDraw GX Graphics /

Chapter 5 - Bitmap Shapes / Bitmap Shapes Reference

Functions / Creating Bitmaps

GXNewBitmap

You can use the GXNewBitmap function to create a new bitmap shape.

gxShape GXNewBitmap(const gxBitmap *data, 
                    const gxPoint *position);

data

A pointer to a gxBitmap bitmap structure that specifies information about the bitmap shape you want to create.

position

A pointer to a gxPoint structure that indicates the initial position of the upper-right corner of the bitmap. You may set this parameter to nil to indicate (0.0, 0.0).

function result

A reference to the newly created bitmap shape.

DESCRIPTION

The GXNewBitmap function creates a new bitmap shape and returns a reference to that shape as its function result.

You specify the initial position of the new bitmap in the position parameter, and you specify the rest of the bitmap geometry by creating a gxBitmap structure and passing a pointer to it in the data parameter.

You must provide values for the width, height, and pixelSize fields of the gxBitmap structure.

Implementation Note

Version 1.0 of QuickDraw GX limits the bitmap width and the bitmap height to 32,767.

You may specify the pixel image in the image field of the bitmap geometry structure, or you may set this field to nil, in which case QuickDraw GX allocates memory for the pixel image based on the requested width, height, and pixel size. If you supply the pixel image, you must also supply an appropriate value in the rowBytes field of the bitmap geometry structure. If QuickDraw GX allocates the pixel image, you should initialize the rowBytes field to 0.

You may indicate a color space for the bitmap in the space field of the bitmap geometry structure, but the pixel size of that color space must match the pixel size you specify in the pixelSize field. If you specify the gxNoSpace constant for the space field, QuickDraw GX chooses a color space for you:

• If you indicate in the pixelSize field a pixel size of 16 or 32, QuickDraw GX chooses the gxRGB16Space color space or the gxRGB32Space color space, respectively.
• If you indicate in the pixelSize field a pixel size of 1, 2, 4, or 8, QuickDraw GX chooses the gxIndexedSpace color space, and creates a default color set of the appropriate size.

If you indicate the gxIndexedSpace color space for the space field, you must provide a color set in the set field.

In the profile field, you may provide a reference to a color profile describing the color matching information for the device on which the bitmap was created, or you may set this field to nil.

SPECIAL CONSIDERATIONS

If no error results, the GXNewBitmap function creates a bitmap shape; you are responsible for disposing of this shape when you no longer need it. See Inside Macintosh: QuickDraw GX Objects for information about creating and disposing of shapes.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
size_of_bitmap_exceeds_implementation_limit
parameter_is_nil	(debugging version)
invalid_pixelSize	(debugging version)
bitmap_height_negative	(debugging version)
bitmap_width_negative	(debugging version)
bitmap_height_negative	(debugging version)
bitmap_rowBytes_negative	(debugging version)
bitmap_rowBytes_too_small	(debugging version)
bitmap_rowBytes_not_aligned	(debugging version)
bitmap_ptr_not_aligned	(debugging version)
bitmap_rowBytes_must_be_specified_for_user_image_buffer
	(debugging version)
colorSpace_out_of_range	(debugging version)
Warnings
shape_access_not_allowed	(debugging version)

SEE ALSO

For examples using this function, see "Creating and Drawing Bitmaps" beginning on page 5-15.

For information about the gxBitmap structure, see "The Bitmap Geometry Structure" beginning on page 5-62.

For information about bitmap width, height, and pixel size, see "Bitmap Geometries" beginning on page 5-5.

For information about disposing of bitmap shapes, see the description of the GXDisposeShape function, which is in the chapter "Shape Objects" in Inside Macintosh: QuickDraw GX Objects.

For a complete discussion of the QuickDraw GX color architecture, see the chapter "Color and Color-Related Objects" in Inside Macintosh: QuickDraw GX Objects.

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help